[ci]: gate the public API surface and the published package shape - #1471

The published package exposes 202 subpath entries, and what each one declares
is only visible in the generated .d.ts tree — which the build throws away. So a
change like dropping a context action or turning Promise<void> into void leaves
no trace in the diff: tsc stays green because the library is internally
consistent, and the break surfaces in a customer's build instead of ours.

`yarn api:snapshot` walks the entry points in rollup.module-exports.mjs, follows
re-exports and inline import types through dist/types, and writes the reachable
declarations to api/surface.d.ts. Internal modules that no entry point reaches
are left out — 294 of 546 files survive the filter.

The file is generated, never edited. Regenerating it twice over one build gives
a byte-identical result.

Recording each declaration file verbatim under its path meant the
snapshot moved whenever a path did. Renaming one internal helper rewrote
seven lines — a path header and six import specifiers — with no
declaration body touched, and the build failed with "Public API surface
changed". Moving that file across directories churned 46. A gate that
fails on changes it has no opinion about is one reviewers learn to skim,
and the worth of this file is that an empty diff settles the question.

Internal declarations are now emitted one block per symbol, keyed by the
symbol; several declarations sharing a name in one file are one symbol,
as the const-plus-type pair behind an enum is. Entry points keep whole-
file blocks, keyed by the public subpath: which symbols a public module
exports is itself the contract, and discarding that is what makes a
purely symbol-keyed snapshot unsafe. Move a type out of
GroupChannel/components/TypingIndicator without re-exporting it and the
subpath stops exporting it, while a snapshot that only records "this
symbol exists somewhere" reports nothing. Here it moves 10 lines.

A symbol is identified by what it declares and by what that declaration
refers to — imported types and types declared beside it alike — resolved
to a fixed point that ends when the keys stop moving rather than after a
set number of passes. A chain of aliases is as long as someone wrote it,
and a difference at its far end still has to reach the name a public
path exports; each pass re-renders only the symbols whose references
moved — tracked as the keys a rendering actually read, not scraped back
out of its text, so that a reference wearing a type-only marker or
sitting inside a namespace still counts, and carried along when a second
declaration reuses a lookup the first one already made — which is what
keeps a five-hundred-deep chain to under a second instead of forty. Two
interfaces that read identically but reach for different types are told
apart, and a reference carries the same key its block does.

A reference names the symbol it reaches for rather than the file that
happens to hold it, so an unrelated export joining that file moves
nothing. Names are followed to their declaration through aliases,
through a binding that was imported and then exported on, through a
namespace, and out to a package, whose specifier is kept since that is
as far as this repository can see. What a module publishes a name as and
what it calls that name inside itself belong to two namespaces, and each
is followed on its own terms: an export name through the module's export
list, its explicit re-exports and its stars; a local name through its
declarations and its imports; the first handing to the second where an
export list renames on the way out. One lookup answering for both is
wrong in both directions — a module that publishes one local name under
another's sends that other name to the wrong declaration, and a name
reaches a declaration through an `import type` the module never
exported, which is where the ChannelSettings entry had been picking up a
type-only marker it has no claim to. `default` is an export name like
the rest, reached through a rename, a re-export, or a plain `export
default`, rather than by matching the text of the last. A walk after one
name records the name it was after at each module it passed and not the
module alone, in both namespaces: arriving at a file a second time for a
different export is how a pair of barrels that hand names to each other
reads, and calling that a circle abandons the walk one hop short of the
declaration. Whether a name leaves type-only
travels with it, because that is the difference between a consumer
constructing a class and failing to.

Two forms point at the module because the module is what they mean —
`export *` and `import * as` — and a module is keyed by what it exports:
every exported name, the symbol it resolves to, and whether it leaves
type-only. A star is spread before anything written out beside it — a
declaration, a local export list, an explicit re-export — so those win
the way TypeScript gives them, both when a module's exports are read and
when a single name is chased to its declaration. What it spreads is
every exported name but `default`, which the language does not forward:
take away the explicit default re-export standing beside a star and the
module has stopped offering a default. A namespace a module imports and
then exports means the module it was taken from, whether it goes out
under that name or another. `export * as` publishes
one name rather than spreading a module, and is recorded that way; every
star that leaves for a package keeps the package it left for, including
when a barrel passes several of them on at once. Modules that re-export
each other as namespaces would otherwise walk in a circle, so each walk
remembers where it has been — down its own path, so that two branches
reaching the same module are not mistaken for a loop, and through a
named re-export, which is another way into the same circle. Breaking the
circle keeps which module it turned back to, since turning back to one
module is not the same contract as turning back to another — by where it
sits on the path, so that modules which declare nothing of their own and
only pass names through are still told apart. A result reached that way
belongs to the path that found it, so it stays out of the cache rather
than being handed to the next reader, whose path may differ and whose
file names have nothing to do with the contract, which holds for a
circle of plain stars as much as for one of namespaces. An internal
barrel is otherwise free to drop a name, rename one, narrow one to a
type or repoint one elsewhere while the snapshot stays still.

A block carries the references that bind the names it uses, and only
those. Every import is split one name per line — package imports
included, their specifiers left alone since they name another package's
contract — and the set is computed from every local binding a statement
introduces, named, aliased, default and namespace alike. Attaching a
whole statement instead would pull in names the declaration never
mentions, which is enough to give one shared declaration two different
bodies and split it into two blocks.

Checked against real builds rather than edited declarations. Five
reorganisations that leave the public surface alone produce no diff at
all: rename, directory move, split behind a barrel, moving a declaration
between internal modules, and moving an entry's source while its subpath
stays. Five real changes still show — a changed internal signature (2
lines), a new public export (1), an entry losing a symbol (10), an entry
removed (63), and a prop added to three same-named public types (3). Two
lines is what a symbol whose name is its own alone costs; where a name is
shared, its key carries a digest of what the symbol declares, so a
one-line change moves the key along with the body and reads as twelve.

The entry block draws the boundary. Moving a declaration out of a public
module shows at 11 lines even when a re-export keeps the subpath
exporting it, because the block records that module verbatim. That is
the same property that lets the snapshot see a subpath lose a symbol, so
the two come together; resolving re-exports into the block instead would
expand every entry's closure into it.

Nothing is dropped in the move: every declaration line of all 294
collected files is present, along with all 725 exported names, 93
@deprecated tags, and 201 of the 202 public subpaths — the one left out
is vendored JavaScript, which the compiler emits no declarations for and
so has no surface to record. All 730 block keys are unique, every
reference either names a block, a module, or a package, and the file
regenerates byte-identically in under two seconds — on any machine.
Blocks are laid out by comparing their keys as strings rather than by a
collation, which changes with the shell's locale: under a
Turkish one the old comparator moved six lines on its own, and a gate
read by `git diff --quiet` would have called that a changed public
surface.

Symbol-level extraction can shrink silently — a declaration the splitter
fails to recognise leaves no trace, and a smaller snapshot reads as a
clean surface. The spec asserts every line of every collected file
survives, that keys stay unique, that a block keeps the reference
binding each name it uses and none it does not, and that a reference
does not move when the file behind it gains an unrelated export. It
covers the shapes that are easy to drop or to over-collect: a
declaration behind a doc comment, a file-level comment ahead of the
imports, a module's local export list, a side-effect import with no name
to attach it to, a binding that is not the first name in its import, a
default and named import sharing one statement, and the const-and-type
pair one name can stand for, where keeping only the declaration written
last drops the other without narrowing anything the snapshot reports.
Each was confirmed by reverting the fix and watching the suite go red.

A module written for Node's ESM resolution names its neighbour with the
extension that neighbour will have at runtime — `export { Foo } from
'./foo.js'` — and declaration emit keeps the specifier as written while
emitting the target as `foo.d.ts`. Probing for `foo.js.d.ts` and
`foo.js/index.d.ts` finds neither, so the target never joins the
collected set and the snapshot holds no record of what `Foo` is:
changing it leaves the file byte-identical while a consumer stops
compiling. A gate that reports nothing is worse than no gate, because an
empty diff is read as an answer.

The runtime extension is now substituted the way the compiler does it
before the candidates are probed, and the substituted form is tried
first: `.js` and `.jsx` stand for a `.d.ts`, `.mjs` and `.cjs` for a
`.d.mts` and a `.d.cts`. Where none of those exist the specifier is read
literally, again as the compiler reads it — `./foo.cjs` beside both a
`foo.ts` and a `foo.cjs.ts` means the second, and letting a bare `.d.ts`
stand in for the missing `.d.cts` would answer with the first. A
specifier that names a declaration file outright is taken as it stands:
`import type { Foo } from './foo.d.ts'` is what the compiler suggests
when it turns the plain import down, it type checks, and declaration
emit keeps it word for word. Nothing in this package spells an extension
out today, so the snapshot does not move — the point is that being right
about it costs nothing before something does.

Checked by resolving every arrangement of the files a specifier could
mean, 112 of them, against the compiler's own answer.

Covered by two conformance cases, where the compiler emits the
declarations, the type behind the specifier changes, and the consumer
and the snapshot have to agree, and by three tests over the resolver
itself, since `.jsx` needs a compiler flag the conformance fixtures do
not set and a declaration file is not re-emitted into an output
directory at all. Dropping the substitution fails two of the tests and
one of the cases; keeping it but letting the bare `.d.ts` stand in fails
one of each; taking the declaration extension away fails one test and
puts four arrangements back out of step with the compiler.

Two more ways a declaration went unread. The snapshot is only as good as
the set of files it reaches, and a file it never reaches is a change it
can never report — the diff comes back empty, and an empty diff is read
as an answer.

A triple-slash `<reference path="...">` names a declaration the way an
import specifier does, and a public signature can rest on a global it
brings in. Only `from` and `import()` were being scanned, so the
referenced file stayed outside the collected set and whatever it
declared could change unremarked. Reference paths are followed now
alongside the specifiers, and it is the compiler's own directive parser
that reads them: matching the shape by hand went wrong in six of
eighteen spellings, once by missing a file the compiler reads — an
attribute name is not case sensitive — and five times by collecting one
it does not, among them a directive with no closing slash and a
directive quoted inside a string.

A default export carries the name of whatever it declares, so an
interface as well as a function or a class — those three and no others,
since an enum or a namespace cannot be default-exported at all. Reading
`export default interface Shape` as anonymous gives two modules that
default-export different shapes the
same export signature, and so the same module key: point an entry at the
other one and nothing moves while a consumer stops compiling. This
package already has such a module, under `modules/App`, though nothing
reaches it by module key today.

Neither changes the snapshot; reading the directives costs the run about
a third of a second, spent once. Covered by two conformance cases, where
the compiler emits the declarations, the type behind the reference
changes, and the consumer and the snapshot have to agree, and by three
tests over the walk itself, one of them holding the directive grammar to
what the compiler accepts. Reverting either fix fails one case and one
test; the default one has to swap which module an entry points at rather
than edit a type in place, since editing one rewrites its block and
would pass whether the module key were right or not.

One statement can bind several names — `export declare const foo = "",
bar = 1;` is what declaration emit gives back for a source that wrote
them together — and only the first was being recorded. The second
belonged to no symbol, so a reference to it resolved to nothing and
every module that declared a name by that spelling folded to the same
key. Point a public entry at a different one of them and the snapshot
holds still while a consumer stops compiling. `const enum E` went the
same way for a different reason: the reader took `const` for the whole
of the declaration and called the thing `enum`.

Every name a statement binds is recorded now, against the statement they
share. Which names a declaration refers to is then read from the shape
of the block rather than from its text, because an identifier sitting
where a name is being declared refers to nothing, while the same
identifier in a type position refers to something. Both halves of that
matter and they pull opposite ways: a value can be typed by a type of
the same name declared beside it, and losing that reference makes two
unlike modules read alike, while counting the name written beside it
makes two names depend on each other, and then an unrelated module
leaving the tree moves both of their keys. The exception is a property
keyed by a name rather than labelled with one — `[KEY]: string` is a
reference to the `KEY` declared above it, and that subtree is read
rather than skipped with the rest of the name.

The names are read with the compiler's parser rather than by splitting
on commas, because the commas that matter are not the only ones on the
line: `Map<string, number>` and `(a: string, b: number) => void` each
carry one that binds nothing. Only statements that open with `const`,
`let` or `var` are parsed for their names — everything else takes its
name from the declaration line, as before — so the run is no slower.

One block moves: a `_default` whose property happens to carry the name
of a declaration in the same file was depending on it, though the
property's type is written out in full and never names it. Changing that
declaration still moves the block, through its body. Nothing else here
writes two names into one statement or declares a `const enum`, so the
rest of the snapshot stands.

Covered by six conformance cases that each hold a public entry still
while the modules behind it move, and by eight tests over the reader,
one of them holding the commas inside a type. Recording only the first
name again fails two cases and three tests; reading the const enum by
the line fails one of each; leaving out every name written beside the
one being keyed fails one of each; taking the declaration sites for
references fails one case and two tests; and skipping a computed
property name with the rest of the name fails two cases and one test.

Two more ways the walk and the module signature lost track of something a
consumer can feel.

A side-effect import names a declaration as surely as one with a `from`
clause. `import './augment';` is how a module brings in a global or an
augmentation, and a public signature can rest on what it declares, but
only specifiers with a `from` or an `import()` were being scanned, so the
file stayed outside the collected set and whatever it declared could
change unremarked. The compiler's preprocessor already reads that file
for its reference directives; its list of imported files is read along
with them now, and the relative ones are followed.

A module that default-exports something without naming it —
`export default class { ... }` — had that recorded as the word
`anonymous`, so two such modules had the same export signature and the
same module key. Point a public alias at the other one and nothing moves
while a consumer's type changes underneath. The declaration is in the
snapshot already, under a key derived from what it says; the signature
carries that key now instead of a word that means nothing.

Neither changes the snapshot: nothing here imports a declaration for its
side effect — all 114 bare relative imports in the collected declarations
are stylesheets — and nothing default-exports without a name. Covered by
a conformance case each, both of which swap which of two modules a public
entry reaches for, and by a test each over the walk and the snapshot.
Reverting either fails one case and one test.